package edu.hawaii.senin.iclouds.basics;

import java.util.Iterator;

/**
 * Encapsulates population for the accounting.
 *
 * @author Pavel Senin
 *
 */
public interface AbstractPopulation extends Iterable<Specie> {

  /**
   * Adds unknown specie type into population.
   *
   * @param specieName the specie name.
   * @param amount the amount of those to add.
   * @return some debug output.
   */
  public String addProduct(String specieName, Long amount);

  /**
   * Adds specie into population.
   *
   * @param spName the specie name.
   * @param sp the specie itself
   * @param amnt the amount of species to add
   * @throws PopulationException if such a specie already within the population.
   */
  public void addSpecie(String spName, Specie sp, Long amnt) throws PopulationException;

  /**
   * Reports whether or not the population contains the specie specified.
   *
   * @param specieName the specie name.
   * @return true if contains.
   */
  public boolean contains(String specieName);

  /**
   * Decrements specie accumulator value by given.
   *
   * @param spName specie name.
   * @param value increment value.
   * @throws PopulationException if specie is not found.
   */
  public void decrementSpecieAccumulator(String spName, Long value) throws PopulationException;

  /**
   * Reports number of species in population.
   *
   * @return number of species.
   */
  public Integer getPopulationSpeciesNum();

  /**
   * Reports total size of population.
   *
   * @return the total size of population.
   */
  public Long getPopulationTotalSize();

  /**
   * Reports specie specified.
   *
   * @param spName the specie name.
   * @return the querying specie.
   */
  public Specie getSpecie(String spName);

  /**
   * Reports particular specie volume.
   *
   * @param spName the specie name.
   * @return the volume.
   * @throws PopulationException if specie is not found.
   */
  public Long getSpecieVolume(String spName) throws PopulationException;

  /**
   * Increments specie accumulator value by given.
   *
   * @param spName specie name.
   * @param value increment value.
   * @throws PopulationException if specie is not found.
   */
  public void incrementSpecieAccumulator(String spName, Long value) throws PopulationException;

  /**
   * Provides iterator over species within the population.
   *
   * @return the iterator over the species.
   */
  public Iterator<Specie> iterator();

  /**
   * Removes the specie entry from the population.
   *
   * @param specieName the specie name to remove.
   */
  public void removeSpecie(String specieName);

}
